Tone Description Structure19

Tone Description Structure

A tone description structure provides the information needed to produce a specific musical sound. The tune header has a tone description for each instrument used. Tone descriptions are also used in the tone description atoms of atomic instruments. The tone description structure is defined by the ToneDescription data type.

struct ToneDescription {
    BigEndianOSType             synthesizerType;
    Str31                       synthesizerName;
    Str31                       instrumentName;
    BigEndianLong               instrumentNumber;
    BigEndianLong               gmNumber;
};
typedef struct ToneDescription ToneDescription;

synthesizerType

The synthesizer type. See "Synthesizer Type Constants" for possible types. A value of 0 specifies that any type of synthesizer is acceptable.

synthesizerName

The name of the synthesizer component instance. A value of 0 specifies that the name can be ignored.

instrumentName

The name of the instrument to use.

instrumentNumber

The instrument number of the instrument to use. This value, which must be in the range 1-262143, can specify General MIDI and GS instruments as well as other instruments (see Table 9 ). The instrument specified by this field is used if it is available; if not, the instrument specified by the gmNumber field is used. If neither of the instruments specified by the instrumentNumber or gmNumber fields is available, the instrument specified by the instrumentName field is used. Finally, if none of these fields specifies an instrument that is available, no tone is played.

gmNumber

The instrument number of a General MIDI or GS instrument to use if the instrument specified by the instrumentNumber field is not available. This value, which must be in the range 1-16383, can specify only General MIDI and GS instruments (see Table 9 ). The instrument specified by the instrumentNumber field is used if it is available; if not, the instrument specified by the gmNumber field is used. If neither of the instruments specified by the instrumentNumber or gmNumber fields is available, the instrument specified by the instrumentName field is used. Finally, if none of these fields specifies an instrument that is available, no tone is played.

GS instruments conform to extensions defined by Roland Corporation to the General MIDI specifications. For information about these extensions, see

http://www.rolandcorp.com/vsc/gs1.html

on the World Wide Web.

Table 9 Instrument number values

Range descriptions

GM Instrument: An instrument number in this range specifies a standard General MIDI instrument which should sound the same on all synthesizers that support General MIDI.
GM Drumkit: An instrument number in this range specifies a standard General MIDI drumkit instrument which should sound the same on all synthesizers that support General MIDI.
GS Instrument: An instrument number in this range specifies a standard GS instrument which should sound the same on all synthesizers that support the Roland GS extensions to General MIDI.
ROM Instrument: An instrument number in this range specifies an instrument of a synthesizer that not a standard General MIDI or GS instrument.
User Instrument: Instruments number in this range are transient and are assigned when necessary for additional instruments, such as instruments in a newly installed GS library or custom instruments for a game. Applications should refer to these additional instruments by name rather by number.
Internal Index: An instrument index value returned by the MusicFindTone function that can be passed immediately in a call to MusicSetPartInstrumentNumber . Values in this range are not persistent and should never be stored or used in any other way.